---
title: Sidebar Navigation
description: Learn how to set up and customize your Starlight site’s sidebar navigation links.
---

import { FileTree } from '@astrojs/starlight/components';
import SidebarPreview from '~/components/sidebar-preview.astro';

A well-organized sidebar is key to a good documentation as it is one of the main ways users will navigate your site. Starlight provides a complete set of options to customize your sidebar layout and content.

## Default sidebar

By default, Starlight will automatically generate a sidebar based on the filesystem structure of your documentation, using each file's `title` property as the sidebar entry.

For example, given the following file structure:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - andromeda.md
        - orion.md
      - stars/
        - betelgeuse.md

</FileTree>

The following sidebar will be automatically generated:

<SidebarPreview
	config={[
		{
			label: 'constellations',
			items: [
				{ label: 'Andromeda', link: '' },
				{ label: 'Orion', link: '' },
			],
		},
		{
			label: 'stars',
			items: [{ label: 'Betelgeuse', link: '' }],
		},
	]}
/>

Learn more about autogenerated sidebars in the [autogenerated groups](#autogenerated-groups) section.

## Add links and link groups

To configure your sidebar links and groups of links (within a collapsible header), use the [`starlight.sidebar`](/reference/configuration/#sidebar) property in `astro.config.mjs`.

By combining links and groups, you can create a wide variety of sidebar layouts.

### Internal links

Add a link to a page in `src/content/docs/` using an object with the `slug` property.
The linked page’s title will be used as the label by default.

For example, with the following configuration:

```js "slug:"
starlight({
	sidebar: [
		{ slug: 'constellations/andromeda' },
		{ slug: 'constellations/orion' },
	],
});
```

And the following file structure:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - andromeda.md
        - orion.md

</FileTree>

The following sidebar will be generated:

<SidebarPreview
	config={[
		{ label: 'Andromeda', link: '' },
		{ label: 'Orion', link: '' },
	]}
/>

To override the values inferred from a linked page’s frontmatter, you can add `label`, [`translations`](#internationalization), and [`attrs`](#custom-html-attributes) properties.

See ["Customizing autogenerated links"](#customizing-autogenerated-links-in-frontmatter) for more details about controlling the sidebar appearance from page frontmatter.

#### Shorthand for internal links

Internal links can also be specified by providing only a string for the page slug as a shorthand.

For example, the following configuration is equivalent to the configuration above, which used `slug`:

```js "slug:"
starlight({
	sidebar: ['constellations/andromeda', 'constellations/orion'],
});
```

### Other links

Add a link to an external or non-docs page using an object with `label` and `link` properties.

```js "label:" "link:"
starlight({
	sidebar: [
		// A link to a non-docs page on this site.
		{ label: 'Meteor Store', link: '/shop/' },
		// An external link to the NASA website.
		{ label: 'NASA', link: 'https://www.nasa.gov/' },
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{ label: 'Meteor Store', link: '' },
		{ label: 'NASA', link: 'https://www.nasa.gov/' },
	]}
/>

### Groups

You can add structure to your sidebar by grouping related links together under a collapsible heading.
Groups can contain both links and other sub-groups.

Add a group using an object with `label` and `items` properties.
The `label` will be used as the heading for the group.
Add links or subgroups to the `items` array.

```js /^\s*(label:|items:)/
starlight({
	sidebar: [
		// A group of links labelled "Constellations".
		{
			label: 'Constellations',
			items: [
				'constellations/carina',
				'constellations/centaurus',
				// A nested group of links for seasonal constellations.
				{
					label: 'Seasonal',
					items: [
						'constellations/andromeda',
						'constellations/orion',
						'constellations/ursa-minor',
					],
				},
			],
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constellations',
			items: [
				{ label: 'Carina', link: '' },
				{ label: 'Centaurus', link: '' },
				{
					label: 'Seasonal',
					items: [
						{ label: 'Andromeda', link: '' },
						{ label: 'Orion', link: '' },
						{ label: 'Ursa Minor', link: '' },
					],
				},
			],
		},
	]}
/>

### Autogenerated groups

Starlight can automatically generate a group in your sidebar based on a directory of your docs.
This is helpful when you do not want to manually enter each sidebar item in a group.

By default, pages are sorted in alphabetical order according to the file [`slug`](/reference/route-data/#slug).

Add an autogenerated group using an object with `label` and `autogenerate` properties. Your `autogenerate` configuration must specify the `directory` to use for sidebar entries. For example, with the following configuration:

```js "label:" "autogenerate:"
starlight({
	sidebar: [
		{
			label: 'Constellations',
			// Autogenerate a group of links for the 'constellations' directory.
			autogenerate: { directory: 'constellations' },
		},
	],
});
```

And the following file structure:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - carina.md
        - centaurus.md
        - seasonal/
          - andromeda.md

</FileTree>

The following sidebar will be generated:

<SidebarPreview
	config={[
		{
			label: 'Constellations',
			items: [
				{ label: 'Carina', link: '' },
				{ label: 'Centaurus', link: '' },
				{
					label: 'seasonal',
					items: [{ label: 'Andromeda', link: '' }],
				},
			],
		},
	]}
/>

## Customizing autogenerated links in frontmatter

Use the [`sidebar` frontmatter field](/reference/frontmatter/#sidebar) in individual pages to customize autogenerated links.

Sidebar frontmatter options allow you to set a [custom label](/reference/frontmatter/#label), use [custom attributes](/reference/frontmatter/#attrs), add a [badge](/reference/frontmatter/#badge) to a link, [hide](/reference/frontmatter/#hidden) a link from the sidebar, or define a [custom sort weighting](/reference/frontmatter/#order).

```md "sidebar:"
---
# src/content/docs/example.md
title: My page
sidebar:
  # Set a custom label for the link
  label: Custom sidebar label
  # Set a custom order for the link (lower numbers are displayed higher up)
  order: 2
  # Add a badge to the link
  badge:
    text: New
    variant: tip
---
```

An autogenerated group including a page with the frontmatter above will generate the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Guides',
			items: [
				{ label: 'A page', link: '' },
				{
					label: 'Custom sidebar label',
					link: '',
					badge: { text: 'New', variant: 'tip' },
				},
				{ label: 'Another page', link: '' },
			],
		},
	]}
/>

:::note
The `sidebar` frontmatter configuration is only used for links in autogenerated groups and docs links defined with the `slug` property. It does not apply to links defined with the `link` property.
:::

## Badges

Links, groups, and autogenerated groups can also include a `badge` property to display a badge next to their label.

```js {9,16}
starlight({
	sidebar: [
		{
			label: 'Stars',
			items: [
				// A link with a "Supergiant" badge.
				{
					slug: 'stars/persei',
					badge: 'Supergiant',
				},
			],
		},
		// An autogenerated group with an "Outdated" badge.
		{
			label: 'Moons',
			badge: 'Outdated',
			autogenerate: { directory: 'moons' },
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Stars',
			items: [
				{
					label: 'Persei',
					link: '',
					badge: { text: 'Supergiant', variant: 'default' },
				},
			],
		},
		{
			label: 'Moons',
			badge: { text: 'Outdated', variant: 'default' },
			items: [
				{
					label: 'Io',
					link: '',
				},
				{
					label: 'Europa',
					link: '',
				},
				{
					label: 'Ganymede',
					link: '',
				},
			],
		},
	]}
/>

### Badge variants and custom styling

Customize the badge styling using an object with `text`, `variant`, and `class` properties.

The `text` represents the content to display (e.g. "New").
By default, the badge will use the accent color of your site. To use a built-in badge style, set the `variant` property to one of the following values: `note`, `tip`, `danger`, `caution` or `success`.

Optionally, you can create a custom badge style by setting the `class` property to a CSS class name.

```js {9}
starlight({
	sidebar: [
		{
			label: 'Stars',
			items: [
				// A link with a yellow "Stub" badge.
				{
					slug: 'stars/sirius',
					badge: { text: 'Stub', variant: 'caution' },
				},
			],
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Stars',
			items: [
				{
					label: 'Sirius',
					link: '',
					badge: { text: 'Stub', variant: 'caution' },
				},
			],
		},
	]}
/>

Learn more about [using and customizing badges](/components/badges/#usage).

## Custom HTML attributes

Links can also include an `attrs` property to add custom HTML attributes to the link element.

In the following example, `attrs` is used to add a `target="_blank"` attribute, so that the link opens in a new tab, and to apply a custom `style` attribute to italicize the link label:

```js {10}
starlight({
	sidebar: [
		{
			label: 'Resources',
			items: [
				// An external link to the NASA website opening in a new tab.
				{
					label: 'NASA',
					link: 'https://www.nasa.gov/',
					attrs: { target: '_blank', style: 'font-style: italic' },
				},
			],
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Resources',
			items: [
				{
					label: 'NASA',
					link: 'https://www.nasa.gov/',
					attrs: {
						target: '_blank',
						style: 'font-style: italic',
					},
				},
			],
		},
	]}
/>

### Custom HTML attributes for autogenerated links

Customize HTML attributes of all links in [autogenerated groups](#autogenerated-groups) by defining the `attrs` property in the `autogenerate` configuration.
Individual pages can specify custom attributes using the [`sidebar.attrs` frontmatter field](/reference/frontmatter/#attrs) which will be merged with the `autogenerate.attrs` configuration.

For example, with the following configuration:

```js {9}
starlight({
	sidebar: [
		{
			label: 'Constellations',
			autogenerate: {
				// Autogenerate a group of links for the 'constellations' directory.
				directory: 'constellations',
				// Italicize all link labels in this group.
				attrs: { style: 'font-style: italic' },
			},
		},
	],
});
```

And the following file structure:

<FileTree>

- src/
  - content/
    - docs/
      - constellations/
        - carina.md
        - centaurus.md
        - seasonal/
          - andromeda.md

</FileTree>

The following sidebar will be generated with all autogenerated links italicized:

<SidebarPreview
	config={[
		{
			label: 'Constellations',
			items: [
				{ label: 'Carina', link: '', attrs: { style: 'font-style: italic' } },
				{
					label: 'Centaurus',
					link: '',
					attrs: { style: 'font-style: italic' },
				},
				{
					label: 'seasonal',
					items: [
						{
							label: 'Andromeda',
							link: '',
							attrs: { style: 'font-style: italic' },
						},
					],
				},
			],
		},
	]}
/>

## Internationalization

Use the `translations` property on link and group entries to translate the link or group label for each supported language by specifying a [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) language tag, e.g. `"en"`, `"ar"`, or `"zh-CN"`, as the key and the translated label as the value.
The `label` property will be used for the default locale and for languages without a translation.

```js {5-7,11-13,18-20}
starlight({
	sidebar: [
		{
			label: 'Constellations',
			translations: {
				'pt-BR': 'Constelações',
			},
			items: [
				{
					label: 'Andromeda',
					translations: {
						'pt-BR': 'Andrômeda',
					},
					slug: 'constellations/andromeda',
				},
				{
					label: 'Scorpius',
					translations: {
						'pt-BR': 'Escorpião',
					},
					slug: 'constellations/scorpius',
				},
			],
		},
	],
});
```

Browsing the documentation in Brazilian Portuguese will generate the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constelação',
			items: [
				{ label: 'Andrômeda', link: '' },
				{ label: 'Escorpião', link: '' },
			],
		},
	]}
/>

### Internationalization with internal links

[Internal links](#internal-links) will automatically use translated page titles from content frontmatter by default:

```js {9-10}
starlight({
	sidebar: [
		{
			label: 'Constellations',
			translations: {
				'pt-BR': 'Constelações',
			},
			items: [
				{ slug: 'constellations/andromeda' },
				{ slug: 'constellations/scorpius' },
			],
		},
	],
});
```

Browsing the documentation in Brazilian Portuguese will generate the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constelações',
			items: [
				{ label: 'Andrômeda', link: '' },
				{ label: 'Escorpião', link: '' },
			],
		},
	]}
/>

In multilingual sites, the value of `slug` does not include the language portion of the URL.
For example, if you have pages at `en/intro` and `pt-br/intro`, the slug is `intro` when configuring the sidebar.

### Internationalization with badges

For [badges](#badges), the `text` property can be a string, or for multilingual sites, an object with values for each different locale.
When using the object form, the keys must be [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) tags (e.g. `en`, `ar`, or `zh-CN`):

```js {11-16}
starlight({
	sidebar: [
		{
			label: 'Constellations',
			translations: {
				'pt-BR': 'Constelações',
			},
			items: [
				{
					slug: 'constellations/andromeda',
					badge: {
						text: {
							en: 'New',
							'pt-BR': 'Novo',
						},
					},
				},
			],
		},
	],
});
```

Browsing the documentation in Brazilian Portuguese will generate the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constelações',
			items: [
				{
					label: 'Andrômeda',
					link: '',
					badge: { text: 'Novo', variant: 'default' },
				},
			],
		},
	]}
/>

## Collapsing groups

Groups of links can be collapsed by default by setting the `collapsed` property to `true`.

```js {5-6}
starlight({
	sidebar: [
		{
			label: 'Constellations',
			// Collapse the group by default.
			collapsed: true,
			items: ['constellations/andromeda', 'constellations/orion'],
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constellations',
			collapsed: true,
			items: [
				{ label: 'Andromeda', link: '' },
				{ label: 'Orion', link: '' },
			],
		},
	]}
/>

[Autogenerated groups](#autogenerated-groups) respect the `collapsed` value of their parent group:

```js {5-6}
starlight({
	sidebar: [
		{
			label: 'Constellations',
			// Collapse the group and its autogenerated subgroups by default.
			collapsed: true,
			autogenerate: { directory: 'constellations' },
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constellations',
			collapsed: true,
			items: [
				{ label: 'Carina', link: '' },
				{ label: 'Centaurus', link: '' },
				{
					label: 'seasonal',
					collapsed: true,
					items: [{ label: 'Andromeda', link: '' }],
				},
			],
		},
	]}
/>

This behavior can be overridden by defining the `autogenerate.collapsed` property.

```js {5-7} "collapsed: true"
starlight({
	sidebar: [
		{
			label: 'Constellations',
			// Do not collapse the "Constellations" group but collapse its
			// autogenerated subgroups.
			collapsed: false,
			autogenerate: { directory: 'constellations', collapsed: true },
		},
	],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
	config={[
		{
			label: 'Constellations',
			items: [
				{ label: 'Carina', link: '' },
				{ label: 'Centaurus', link: '' },
				{
					label: 'seasonal',
					collapsed: true,
					items: [{ label: 'Andromeda', link: '' }],
				},
			],
		},
	]}
/>
